Getting Started
This page covers the one-time setup you need before you can run make targets against the servers.
Running make setup-*, update-* or deploy-* targets changes production directly. Only admins do this. If you're not an admin, you still need Vaultwarden access to work with the repo, but you make changes through a pull request and an admin runs the target. See Making Changes.
1. Get the latest main branch
Everything runs from the infrastructure-automation repo on Gitea. The first time, clone it:
git clone https://gitea.abair.ie/ABAIR/infrastructure-automation.git
cd infrastructure-automation
If you already have it, pull the latest main before you do anything else:
git checkout main
git pull
Always pull before running a make target. Running from an old checkout can undo changes other people have already deployed.
You only need the infrastructure-automation repo checked out. Playbooks that build an app from source clone it from Gitea on the server; see Configuring with Ansible. The one exception is synthesis-legacy, whose source repos aren't on Gitea yet.
2. Install Docker and make
Every make target runs inside a Docker container built from docker/Dockerfile. The container has pinned versions of the tools the repo needs:
| Tool | Version |
|---|---|
| ansible-core | 2.17.10 |
| ansible.posix collection | 1.5.4 |
| community.general collection | 12.6.5 |
| Terraform | 1.9.8 |
Bitwarden CLI (bw) | 2026.4.1 |
So you only need Docker and make on your own machine. You don't install Ansible, Terraform or bw yourself, and every admin runs the same versions. On Windows, use WSL2.
On an Apple Silicon Mac the image is still built and run as linux/amd64 (the Makefile passes --platform linux/amd64, because the Bitwarden CLI only ships an x86_64 Linux binary). Docker Desktop emulates it, so keep Use Rosetta for x86_64/amd64 emulation turned on in its settings. It's on by default.
The image builds automatically the first time a target needs it. To build it yourself, or to rebuild it after docker/Dockerfile changes, run:
make docker-build
The container mounts:
- the repo, at
/workspace - your
~/.sshdirectory, so your SSH config and keys work inside it - your SSH agent socket, if
SSH_AUTH_SOCKis set ~/.config/bw-vaultwarden, which holds your Vaultwarden login
Files the container writes into the repo (Terraform state, for example) are owned by your own user, not root.
3. Log in to Vaultwarden
Almost every target pulls its secrets at run time from the team's password vault at vault.abair.ie. That's a self-hosted, Bitwarden-compatible server; see Vaultwarden. Ask an admin for an account if you don't have one.
Once per machine, log in from inside the tooling container:
make docker-shell
# now inside the container:
bw config server https://vault.abair.ie
bw login you@tcd.ie
exit
This uses a separate bw profile (~/.config/bw-vaultwarden), so it doesn't interfere with any personal Bitwarden account.
Once per terminal session, unlock the vault before running other targets:
eval "$(make unlock-bw)"
It asks for your master password without echoing it, then exports BW_SESSION into your shell. Later make targets in that terminal reuse the session. If you see "You are not logged in", do the one-time login above first.
What you can fetch depends on which Vaultwarden collections you belong to. If you aren't a member of an app's collection, fetching that app's secrets comes back empty and the playbook stops with an error. It never deploys an empty .env file.
4. Set up SSH
The hetzner-main VMs sit on a private network (10.0.0.0/24) that you can't reach directly. You reach them by jumping through the Proxmox host. The other servers are reached directly.
The SSH config is kept in Vaultwarden. Log in to vault.abair.ie, open the access collection in the ABAIR organization, and copy the SSH config file into your ~/.ssh/config. Don't change the host names: they are what the Ansible inventories and the Makefile use.
Your public key must already be authorized on each server. SSH access to hetzner-main is also restricted to specific admin IP addresses. Ask an admin to add yours.
Two servers have extra access rules:
- Puca is on the lab network, so it's only reachable from inside TCD. Its firewall only accepts SSH from a short list of addresses, and Ansible normally runs from the lab machine
setanta. See Puca. - Vaultwarden does not accept root logins at all.
5. Check it works
With the vault unlocked, a harmless first check is to SSH to a VM through the jump host:
ssh webserver-vm hostname
Then look at the Makefile Reference for the available targets, or Making Changes for how changes are made. For what admins are typically asked to do, see Common Tasks for Admins.